docs: convention for integration repository structure and naming - #712
docs: convention for integration repository structure and naming#712Maya Wang (mayawang) wants to merge 1 commit into
Conversation
Records where end-to-end integrations live, how their repositories are named, and how fixes they need flow back into core. Trivial demos stay in the core repo; each non-trivial integration gets one dedicated repo under the agent-substrate org; core gaps are closed by making core configurable with defaults unchanged rather than by patching it downstream. Written down before the first integration repositories exist, so that precedent is chosen deliberately rather than inherited from whichever repo happens to be created first. Governance tiers and repository-creation access are called out as open questions rather than answered here.
|
Meta point: the commit doesn't seem to be associating with your account? The git author info should include an email address that you have associated with your github account (you can associate mutliple). |
|
|
||
| - **Generic names** such as `sandbox` or `plugins`, which claim far more ground | ||
| than any one repository covers. | ||
| - **Names that clone a vendor's API or brand**, which quietly commits the |
There was a problem hiding this comment.
this is slightly at odds with the integration bit below, should we limit them to OSS projects or something?
I don't think we have to fully resolve that now, but ... bit tricky
| into suspend-safe actor networking | ||
| ([#465](https://github.com/agent-substrate/substrate/issues/465)). | ||
|
|
||
| The path for those fixes should be short and well-travelled. An integration |
There was a problem hiding this comment.
I don't think integration repositories that we host should exist with any required patches to core, we should always land the patch to core first.
I think it's OK for independent POCs, but for official projects it's embarassing to depend on changes that don't exist in our own upstream yet. Let's just avoid that entirely. We are our own upstream if we're hosting both repos.
I'd drop this section or require no forking of core.
| These are open questions for the maintainers, deliberately left out of scope | ||
| here so they do not block the first repositories: | ||
|
|
||
| - **Governance tiers.** Whether to distinguish "official" from "community" |
There was a problem hiding this comment.
IMHO: let community host their own outside the org. It's confusing to have things that are under our brand but not considered official. Let's just not do that.
2 participants
Summary
Adds
docs/integration-repos.md: where end-to-end integrations live, how theirrepositories are named, and how the fixes they need flow back into core.
The convention in one line — trivial demos stay in the core repo, each
non-trivial integration gets one dedicated repo under the
agent-substrateorg, and core gaps get closed by making core configurable with defaults
unchanged rather than by patching it downstream.
Why now
We are about to create the first real, end-to-end integrations rather than
counter-style demos: a code-execution sandbox, and an always-on agent. Both are
large enough to need their own images, dependencies, and release cadence.
Whichever repository gets created first will set the precedent for every one
after it. This writes the convention down so that precedent is chosen
deliberately instead of inherited by accident.
What it covers
which side something falls on (API keys, external services, third-party
accounts), and why this is a set of peer repos rather than a second org.
(
code-execution-sandbox), integration-named for specific third-partyproducts, named for the product rather than the vendor behind it. Plus what to
avoid: over-broad names, names that clone a vendor's API or brand, and the
redundant
-integrationsuffix.the repo README, and brand/policy edge cases cleared before the repo exists.
accumulate local patches against core bitrot, and the gap they work around
stays invisible to everyone else. So: prefer making core behavior configurable
with defaults unchanged. feat: readyz: make the overall wait timeout configurable per template #487 and Suspend-safe actor networking via injected in-sandbox ingress/egress proxies #465 are linked as illustrations of that
pattern — this PR does not depend on either, and branches from
main.following it, including the third-party-name edge case.
Review
This was announced at the community meeting and circulated as a shared design
doc with a 7-day review window, which has now closed. It synthesizes the
#integrationsthread discussion. Comment history:https://docs.google.com/document/d/1Tb6u0b1XSvWrNpoyD4jdsQaJ58aAgDtQOM18uxujs-8/edit
This PR is the trimmed version: doc-review scaffolding — status block, reviewer
list, self-link — is dropped, and only the durable convention is carried over.
Left open
Two questions are deliberately out of scope, called out in the doc rather than
answered. Both are maintainer calls and neither blocks the first repositories:
integrations with different review bars, as Home Assistant and Obsidian do.
access.
Also in this PR
docs/.CONTRIBUTING.mdgets one sentence pointing there, since "where does myintegration go?" is a question a contributor asks before opening a PR.
Fixes #<issue_number_goes_here>